The Arsenal Files 8/The Arsenal Files Collection #8 (Arsenal Computer) (1996).ISO/prg_gen/swag.zip/READER.DOC

Text File | 1996-11-29 | 21KB | 451 lines

                             READER.EXE v3.13
                           (SWAG packet READER)
                                (c) GDSOFT
                                 May 1996

INTRODUCTION
------------

SWAG (SourceWare Archival Group) is a collection of source code and program
examples for the PASCAL programming language. The material has been donated
by  various  PASCAL  programmers  from  around  the  world,  who  desire to
contribute to the advancement of  one of the greatest programming languages
there is.  MANY THANKS to all  who have contributed. As  such, NO CHARGE OF
ANY KIND IS PERMITTED FOR THIS WORK.

The material has been collected from various network conferences worldwide,
and organized  according to subject.  New material is  added quarterly, and
new SWAG  packets are available  from various BBS  sources on a  FIRST call
basis. See BBS.TXT for current support sites and how your BBS can join.

GETTING STARTED
----------------

The program READER.EXE is a executable program that will allow you to read,
extract or print the contents of  SWAG packets. These packets are organized
according to subject, with each one containing a number of PASCAL "snipets"
on that subject. In the rest of this document, I'll refer to the program as
"READER".

The SWAG packets should be placed ALL together in a directory on your disk.
It is recommended that you create a single directory named '\SWAG'. You can
use the DOS command :

                            mkdir c:\swag

Unpack  the distribution  archives and  place  all  of the  files with  the
extension of "*.SWG" in this directory along with READER.EXE.


USING THE READER
----------------

Using the  reader is really very  simple. Just execute it,  and you will be
presented with a  directory of all of the .SWG  files in the directory that
READER is located in. If you have .SWG files elsewhere on your disk, or for
that matter, any disk on your system,  you can move around the disk to find
them  by  selecting  the  ".."  file  which  will  take  you  to the PARENT
directory. Use the HOME, END and the arrow keys to maneuver around.

ALSO,

The directory window  is search key sensitive. This means  that if you have
.SWG files  or directories listed in  the directory box, you  can just type
the name of the file you want.  For example, pressing 'A' will place you at
the first  entry starting with  'A'. Press 'N',  and you will  jump the the
entry with 'AN...'  if you have one. If  NOT, you will jump the  first file
starting with the letter 'N'.

At the bottom  of the screen you will notice  a menu indicating some cursor
and function keys :

                        F2 - GREP
                        F5 - Toggle STATS

                        <ENTER> - GO
                        ESC - QUIT

F2 calls  the GREP (search)  function. This is  a VERY POWERFUL  and useful
function, but  in order to  use this function,  you MUST have  at least ONE
.SWG file  in the directory  box, and it  MUST be highlighted  !! Place the
cursor any one of the .SWG files,  and press F2. You will be presented with
a prompt window :

                        SWAG Message Base Reader 3.0
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓┌ D:\SWAG\FILES\ ▓▓┌──────────── SOURCEWARE ARCHIVAL GROUP ───────────┐▓▓
▓▓│ [A:\]          │▓▓│                                                  │▓▓
▓▓│ [B:\]          ▓▓▓│ Your SWAG Support Team :                         │▓▓
▓▓│ [C:\]          │▓▓│                                                  │▓▓
▓▓│ [E:\]          │▓▓│ Gayle Davis  Goshen, Indiana  46526              │▓▓
▓▓│ ..\            │▓▓│ Kerry Sokalsky  North York, Ontario  M2P 1L2     │▓▓
▓▓│ ANSI.SWG       │▓▓│                                                  │▓▓
▓▓│ ARCHIVES.SWG   │▓▓│ About SWAG :                                     │▓▓
▓▓│ CHARS.SWG      │▓▓│                                                  │▓▓
▓▓│ CMDLINE.SWG    │▓▓│ SWAG is a collection of source code and program  │▓▓
▓▓│ COLOR.SWG      │▓▓│ examples for the PASCAL program language.   The  │▓▓
▓▓│ COM┌────────────────────── GREP SWAG Files ───────────────────────┐L │▓▓
▓▓│ COP│  Search For: CURSOR&CRT|ANSI&FILE                            │n │▓▓
▓▓│ CRC└──────────────────────────────────────────────────────────────┘t │▓▓
▓▓│ CRT.SWG        │▓▓│ programming platforms available today.           │▓▓
▓▓│ CURSOR.SWG     │▓▓│                                                  │▓▓
▓▓│ DATATYPE.SWG   │▓▓│ MUCH THANKS AND GRATITUDE TO ALL CONTRIBUTORS !! │▓▓
▓▓│ DATETIME.SWG   │▓▓│ NO Charge of ANY kind is permitted for this work │▓▓
▓▓└────────────────▓▓│                                                  │▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓└──────────────────────────────────────────────────┘▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓

Enter a string  to search for. You may search  for a multiple occurrence of
substrings using  BOOLEAN operators AND (&)  OR (|). For example,  a search
for  THIS&THAT|THEM&THOSE would  return  all  snipets containing  both ORed
phrases THIS&THAT OR THEM&THOSE.

In BOOLEAN Algebra, the AND operator  takes precedence over the OR operator
(except  when  using  parentheses).  This  is  NOT  the  case with the GREP
function. You  can use the PARENTHESES  () to dictate which  portion of the
search string is  to be processed first. If  multiple levels of parentheses
are used,  the order is RIGHT  to LEFT, starting with  the innermost set of
parentheses, wherever they occur.

As an example, in the phrase ((this|that)&(them&those)), (them&those) would
be processed  before (this|that)) innermost  to outermost. In  other words,
all snipets  will be returned  containing THIS or  THAT AND they  also will
contain (THEM and THOSE).

Within a set  of parentheses, order will be left  to right. Construction of
the search string itself requires combining the desired substrings together
with  the desired  BOOLEAN operators.  Without the  parentheses, the search
string will be processed logically. THIS|THAT&THEM&THOSE will return all of
the snipets  that contain THIS  plus the  ones  that contain THAT  & THEM &
THOSE. You can  see that this is totally different  than what you'll get by
using the parentheses.

Additionally, you can also include a  date in the format MM/DD/YY, and ONLY
records AFTER this  date will be included. If you  enter JUST the date, ALL
SWAG  snipets  AFTER  this  date  will  be  included. For example, entering
CURSOR|ANSI&CRT|05/08/93  would search  the  SWAG  packets for  matches for
CURSOR OR (ANSI  AND CRT) occurring AFTER 05/08/93.  Entering JUST 05/08/93
at the prompt would bring back ALL snipets AFTER 05/08/93 REGARDLESS of the
subject.

Enter  an empty  string as  the search  string, and  READER will return all
snipets since the LAST SWAG release.

READER will search ALL of the  SWAG packet HEADERS in the CURRENT directory
for matches based  on your criteria. A processing box  will appear, and all
occurrences of your  search string(s) or date matches will  be written to a
NEW SWAG file.  Initially, this file is named GREPSWAG.SWG,  and will be in
the current  directory. Upon completion of  this GREP process, you  will be
asked for the  file name. Enter any name AND  directory you choose, and the
file will be RENAMED and moved  to that directory. Pressing ESCAPE WILL NOT
save a file at all. This process allows you to create SWAG files containing
ANY combination of material that you please.

You can  ALSO search the ENTIRE  SWAG snipet buffer for  data. Just enter a
tilde (~) character as the FIRST character on the search line. For instance
to  find all  snipets containing  CRT, you  would enter  ~CRT on the search
line. ONLY  the header of snipets  is searched for matches.  This a way you
can look at all snipets by a certain contributor. You can also use multiple
search criteria  here. For instance,  ~GAYLE DAVIS|GUY MCLOUGHLIN|JOE  BLOW
would bring back  everything for each of these  persons. This search method
is VERY fast as on the headers have  to be read. By the way, the same rules
about AND/OR searching apply when search just the headers.

Beginning with  version 3.0, we added  KEYS to the SWAG  header. This makes
the searching function work MUCH faster,  and you can use EDIT HEADER (CTRL
[H]) function to edit these keys.

OTHER FUNCTION KEYS IN THE MAIN SCREEN
--------------------------------------

ALT[R] lets you rename any of the .SWG files that you have.

[DEL] allow you to DELETE any of the .SWG files. BE CAREFUL HERE !!

[F5] toggles the  STATS function. In order for this  to work, you MUST have
at least ONE .SWG file in the  directory box, and it MUST be highlighted !!
Place  the cursor  any one  of the  .SWG files,  and press  F5. You will be
presented with an  EXPANDED directory list showing the  description of each
.SWG file and the number of snipets in each.

VIEWING, EXTRACTING, PRINTING SWAG SNIPETS
------------------------------------------

Once you have  some .SWG files in the directory  box, press <ENTER> and the
package will be read and you be able to manage the SWAG snipets.

You will be  presented with a list of  all of the snipets contained  in the
package with descriptions for each.

At the bottom of the screen, will be the following menu.


 ▀ F1-Help   ▀ F3-Options  ▀ AltFind   ▀ ┘- Read   ▀ F4-DoTags ▀ ESC-Quit
 ▄▄▄▄▄▄▄▄▄   ▄▄▄▄▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄▄   ▄▄▄▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄▄▄


                F1   - provides some "quick" ALT keys.

                ┌──────────── READER : HELP ───────────┐
                │ Alt F       Find Text                │
                │ Alt S       Sort Index               │
                │ Alt T       Tag ALL                  │
                │ Alt U       UnTag ALL                │
                │ Ctl S       SHELL to DOS             │
                │ Spacebar    Tag Current              │
                │ <ENTER>     Read Item                │
                │                                      │
                │ F1          Help                     │
                │ F3          Program Options          │
                │ F4          Process Tagged Items     │
                │ ESC         Quit Program             │
                └──────────────────────────────────────┘

                F3   - brings up the OPTIONS menu.

                ┌──────────────────────┐
                │  About               │
                │  Sort - (ALT S)      │
                │  Spacebar Tag - ON   │
                │  Colors              │
                │  Dos Shell           │
                │  Screen Lines - 25   │
                └──────────────────────┘

                AltF - Find function
                <CR> - read the snipet
                F4   - Process TAGGED items
                ESC  - Quit


43/50 LINE VIDEO
----------------

You will have the capability of using 43/50 line screens if you have EGA or
better.  The  option  can  be  found  in  the  OPTIONS  menu  (F3).  It  is
automatically  disabled if  the user  doesn't have  the capability.  Select
SCREENLINES, and if you have an EGA/VGA, you'll get 43/50 line mode.

COLORS
------

To be quite  honest, the whole business of allowing  users to change colors
is quite a  problem. It adds a lot  of code to the program,  and more often
than not, it is used only once  by the user. Therefore, the color selection
if VERY limited.

There are four  color group choices available. LIGHTGRAY,  BLUE, CYAN, RED,
GREEN and MAGENTA. Select one that you find pleasing. This will be disabled
on monochrome monitors.

DOS SHELL
---------

You can shell  out to DOS from within  the READER. This ability is  here on
the OPTIONS  menu. You can  ALSO do  this  at ANYTIME by  using CTRL[S] key
sequence.

SORTING
-------

ALT S on the main selection window  brings up the SORT box. The snipets can
be sorted by :

                        ┌────────────────────────────┐
                        │                            │
                        │  Select Sort Field :       │
                        │                            │
                        │         N - NUMBER         │
                        │         F - FROM           │
                        │         S - SUBJECT        │
                        │         D - DATE           │
                        │                            │
                        └────────────────────────────┘


TAGGING ITEMS
-------------

Snipets can be tagged by using the SPACEBAR. SPACEBAR tag can be turned OFF
in the OPTIONS menu.  ALL items can be tagged with ALT  T and untagged with
ALT U. Tagged items can be process  using F4. Tag some files, and Press F4.
You'll be given a choice of Zapping the tagged items, or extracting them to
a directory on your disk.

FINDING TEXT IN THE MAIN SNIPET WINDOW ( SPEED SEARCH)
------------------------------------------------------

You can  use the ALT[F]  key sequence to  find any text  in the main snipet
window.  Alternately, you  can use  the SPEED  SEARCH feature  by just type
letters or numbers, and the cursor  will automatically be moved to the item
that matches  what you are typing.  The search string will  be displayed at
the  bottom  left  corner  of  the  snipet  window,  and  the  cursor  will
automatically  move to  the matching  item. Numbers  are permitted too. Try
entering  '19', and  you will  be moved   to the  19th item  in the  window
assuming there is one.


READING SNIPETS
---------------

Pressing <ENTER> on any of the snipets  allows it to be reviewed. You'll be
presented with the  "snipet" screen and you can use  the menu at the bottom
of the screen :

┌────────────────────────────────────────────────────────────────────────┐
│ ▀ Next(+) ▀ preV(-) ▀ Mark ▀ Find ▀ Extract ▀ Kill ▀ Print ▀ ESC-Quit  │
│ ▄▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄  ▄▄▄▄▄  ▄▄▄▄▄▄▄▄  ▄▄▄▄  ▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄  │
└────────────────────────────────────────────────────────────────────────┘

To accommodate  many of the  QWK reader  users  out there, you  can use the
PLUS(+) and  MINUS(-) keys to  display the NEXT  or PREVIOUS snipet  OR the
SPACEBAR key will display the NEXT snipet.  Also, you can use TAB for NEXT,
and SHIFT+TAB for PREVIOUS.

You can  Mark, Find, Extract, Kill  or Print snipets. If  you have a mouse,
you can select any of these functions by using the LEFT button on any item.


EXTRACTING SNIPETS
------------------

Snipets can be  extract to an ASCII file by  selecting and pressing the 'E'
key. Enter  the filename, and  the data  with  be written out.  If the file
selected is already on  your disk, you will be asked if  you want to APPEND
or OVERWRITE.  You can bring up  a directory selection screen  by using the
DOWN arrow key  while the selection box is on  screen. Select the directory
of your choice.  If you do not enter  a valid path and file  name, you will
receive an error message.

KILLING SNIPETS
---------------

Starting with version  2.9, you are able to delete  (KILL) snipets that you
do not  want for some  reason. BE CAREFUL  HERE !!! Once  deleted, they are
gone forever. Upon exit from the file, the entire .SWG file will be rebuilt
to    eliminate    the    killed    snipet.


EXTRA MENU - CTRL KEYS
----------------------

Pressing the CTRL key brings up the EXTRA menu :

┌────────────────────────────────────────────────────────────────────────┐
│ ▀ Next(+) ▀ preV(-) ▀ Move ▀ Copy ▀ Extract ▀ Header       ▀ ESC-Quit  │
│ ▄▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄  ▄▄▄▄▄  ▄▄▄▄▄▄▄▄  ▄▄▄▄▄▄         ▄▄▄▄▄▄▄▄  │
└────────────────────────────────────────────────────────────────────────┘

.. The HEADER function lets you edit the CONTRIBUTOR, SUBJECT and the KEYS.

.. The MOVE  function lets  you  move  snipets to  another .SWG  file. The
original snipet will deleted from the current file.

..  The COPY function lets  you  copy  snipets to  another .SWG  file. The
original snipet will remain unchanged.


PROCESSING TAGGED SNIPETS
-------------------------

Once you  have tagged a  group of snipets,  you can process  them using F4.
There are  two functions available. ZAP  all tagged items, and  EXTRACT all
tagged items to a directory on your disk.

FINDING TEXT IN SNIPETS
-----------------------

You  can  use  the  (F)ind  command  to  find  text located within the SWAG
snipets. This works JUST LIKE the BORLAND  PASCAL IDE. You can ALSO use the
^Q^F  key sequence  to activate  this function.  Just as  with the  IDE, ^L
displays the NEXT find.

SWAG SNIPETS MARKED WITH CHECKMARK
----------------------------------

If you  see snipets with a  CHECKMARK (#251) beside them,  this indicates a
NEW item  added since the LAST  update. The READER.EXE keeps  track of this
and  marks  these  automatically.  The  checkmark  is  only  there for your
reference.

THE READER INI FILE
-------------------

The READER  program keeps several  of its program  defaults in an  INI file
(simple ASCII) in the same directory  as READER.EXE. Contained in this file
are several items that you can change  to affect the way the program works.
The lines in this file have the format LABEL=VALUE.

The file looks like this :

         COLOR=LIGHTGRAY       (LIGHTGRAY,BLUE,CYAN,RED,GREEN,MAGENTA)
         43/50=NO              (YES or NO)
         SORT=n                (nUMBER,fROM,tO,sUBJECT,cONFERENCE)
         TEXTEXT=PAS           (default extension for extracted files)
         EXTRACTDIR=D:\TEMP\   (default directory for extraction)
         PRINTER=LPT1          (printer port [LPT1,LPT2,LPT3,LPT4])
         SWAGDIR=\SWAG\FILES\  (Wherever you keep them)
                               (NOTE :  This WILL be overridden by the
                                SWAG= environment variable !! )
         SWAGADDS=YES          (Display those BBS adds at the top (YES/NO)
         SWAGSTATS=NO          (Start reader in STAT mode or FILES mode)

You can change this file using any  word processor. I think that you'll get
the idea.


THE SWAG ENVIRONMENT VARIABLE
-----------------------------

Some users reported a considerable delay while SWAG programs looked for the
.SWG files on  their disks. This problem has been  eliminated by adding the
environment varible SWAG to allow total  override of the SWAGDIR= switch in
the READER.INI. Use the command :

                        SET SWAG=yourpath

at the DOS prompt to set this.  This then become the ABSOLUTE location that
READER and other  programs use to as the beginning  path for SWAG files and
WILL OVERRIDE you setting in the READER.INI file.

COMMAND LINE USAGE
------------------

Starting with  this version of the  READER, individual SWAG packets  can be
read  from  the  DOS  command  line.  Simple  type READER swagfilename. For
example, you can look at all of the snipets in ANSI.SWG by typing :

                           READER ANSI.SWG <ENTER>

You don't really need to enter the  extension, as the READER will append it
for you.  If the .SWG  files are not  in the current  directory READER will
look for them somewhere on your current PATH.

XX3402 ENCODED FILES
--------------------

Many  of the  SWAG snipets  contain code  that has  been encoded  using Guy
Mcloughlin's XX3402  encoder. This has  been done due  to the necessity  to
include OBJ  code in the snipet,  and this allows us  a way to do  it. What
this fine  program does is to  create an ASCII encoded  file containing the
BINARY data.  You need to  "CUT" these items  from the snipet,  giving it a
unique name, and  decode it using XX3402. It's really  an easy thing to do.
Once you cut your file out, just execute from the DOS command line :

                        XX3402 d yourfilename

Magically, the file  needed to compile the snipet will  appear !! It's just
that easy. See the file included  with the SWAG distribution XX3402.ZIP for
complete instructions, and  the COMPLETE SOURCE CODE to  this fine program.
Thanks GUY for letting us use XX3402 for SWAG.

We  hope that  you find  the READER   easy to  use, and  the SWAG  material
valuable in development of your PASCAL programs.

ENJOY !!!!! and GOOD PROGRAMMING !!!

Gayle Davis, Kerry Sokalsky and Jeff Fanjoy
SWAG Support Team